Rhapsody Developer Release Copyright 1997 by Apple Computer, Inc. All Rights Reserved.

Rhapsody Developer Release Notes:
Application Framework

The Application Kit is one of the core Yellow Box frameworks. It provides functionality and associated APIs for applications, including objects for graphical user interfaces (GUIs), event-handling mechanisms, drawing and image composition facilities, and application services.

Notes Specific to Developer Release

New Features

The Application Kit includes these new or updated classes (since OPENSTEP 4.2):

NSPICTImageRep

A class for objects that represent PICT images. For the Developer Release, only bitmap PICTs work.

 

NSProgressIndicator

A class for objects that implement a determinate or indeterminate progress indicator. The indeterminate progress indicator can be animated in a separate thread, allowing its use even in computation code that doesn't use the run loop.

 

NSTabView and NSTabViewItem

Classes for displaying multiple views using tabs.

 

NSOutlineView

A subclass of NSTableView that implements an outline representation of hierarchical data. Like NSTableView and NSBrowser objects, NSOutlineView objects use a data source (separate from the delegate) to display the data lazily.

 

NSColor

New factory methods create objects that represent additional user interface colors.

 

NSColorPanel

As does the Font panel, the Color panel now has a Set button. When clicked, it sends a changeColor: message down the responder chain. See the NSColorPanel documentation for details.

 

NSFont

The systemFontOfSize: and boldSystemFontOfSize: methods have been deprecated in favor of the other factory methods returning user-chosen fonts. The function NSConvertGlyphsToPackedGlyphs() was added to allow you to convert an array of NSGlyphs to "packed" glyphs, suitable for passing to PostScript.

 

NSImage and NSBitmapImageRep

NSImage and NSBitmapImageRep can now read GIF, JPEG, and PNG images directly (that is, without the aid of filter services). JPEG and PNG writing is also supported; GIF writing is planned for a future release. Some APIs were added to NSBitmapImageRep to provide support for features found in these image file types.

 

NSBezierPath and NSAffineTransform

These two classes help provide a more complete abstraction in the Application Kit framework layer for graphics operations. NSBezierPath enables standard operations with lines, user-defined paths, and arrays of glyphs, such as stroking, filling, and clipping. It also provides simple bounds computation and hit detection methods. NSAffineTransform provides an abstraction for the graphics transformation matrix.

 

NSGraphicsContext

The abstract superclass for NSDPSContext, this class provides methods to save and restore the graphics state and to change the current graphics context.

 

NSSplitView

The look and feel of the split view has changed significantly. There's no dimple, the split bar is thinner, and you get a resize image when the cursor is over it. You should use the method dividerThickness to determine the correct thickness of the bar.

 

NSScreen

The new method visibleFrame supplies the usable region (without menu or task bar regions) of a given screen.

 

Menu and Pop-up Button Classes

Menus and pop-up buttons have changed significantly since OPENSTEP 4.2. In OPENSTEP 4.2, NSMenu and NSMenuItem claimed they were NSObject subclasses, but they were actually subclasses of NSPanel and NSButtonCell. Although the compiler would warn about panel or cell messages being sent to these objects, they would perform as required at run time. In the new implementation, NSMenu and NSMenuItem are true subclasses of NSObject. If your code is sending messages to these objects—which assume inheritance from NSPanel and NSButtonCell—it will no longer work.

 

NSMenu and NSMenuItem include new APIs and functionality. NSMenuItems may now have titles, key equivalents, images, and state images. NSMenus have a platform-specific menu representation that is in charge of presenting the menu to the user and allowing the user to interact with it. On Mach, the menu representation is an NSMenuView. NSMenuView allows much leeway in the way a menu works and looks. An NSMenuView uses NSMenuItemCells to draw its items. On Windows the menu representation class is currently private (NSMenu's menuRepresentation method will return nil).

 

The NSMenuItem protocol has been deprecated in favor of the NSMenuItem class. Use the class instead of the protocol, which will be dropped from the Application Kit in a future release. There is now a public NSPopUpButtonCell class. See the Application Kit reference documentation for details of the new APIs.

 

Some planned features are not yet implemented, such as tear offs and key-equivalent overrides. You should not have to do anything special to prepare your application for these coming features. Context menus are supported in the Developer Release, but only for systems with two-button mice. Support will be added in a later release support for Control-click context menus. Your code should not have to change, but you should be aware that using the control key for your own special mouse features is probably not a good idea since that modifier key will soon have another meaning.

 

NSSlider

Sliders now support tick marks that identify specific values on the slider continuum. Clicking these tick marks returns the represented value.

 

NSTextView

NSTextView objects can now read HTML files. A delegate method is provided for following HTML links.

 

Delegate methods for clicking on cells have been augmented with an argument to specify the character index of the click; for instance, textView:clickedOnCell:inRect:atIndex: instead of textView:clickedOnCell:inRect:. The old delegate methods will continue to work, but you should plan to replace them with the new ones.

The text system now treats control-L ("form feed") as a container break character. A control-L forces the layout to continue onto the next container. However, the text system also tries to recognize the infinitely-growing container case (which is the usual situation in applications such as TextEdit and Project Builder), and ignores the control-L in these cases.

 

NSApplication

On non-Windows platforms, an application can now choose to quit when the last window is closed. If the application delegate responds to applicationShouldTerminateAfterLastWindowClosed: by returning YES, the application is sent a terminate: message when the last window is closed.

 

On Windows systems there has been no change. If the last window of an application is closed, and if the window contained the application menu, the application is sent the terminate: message by default. The delegate can prevent this by responding NO to applicationShouldTerminateAfterLastWindowClosed:.

 

NSWindow

Instead of miniaturizing, windows now use a feature called WindowShading: when the user clicks the appropriate window control, the window's content view disappears and just the title bar remains (this can be toggled back to the original state). Windows also have a zoom button, which switches a window between a standard (size-to-fit) size and a user size. The standard size can be set by calls to the delegate.

 

A document icon in the title bar gives access to the document represented by the window; users can drag and drop the document directly (this replaces the "Alternate-drag from the miniaturize button" model of OPENSTEP 4.2).

 

NSView

Two new methods in NSView, didAddSubview: and willRemoveSubview:, provide ways to detect subview list changes.

 

NSCell and NSButtonCell

These classes now support mixed-state cells. You can enable this feature with the setAllowsMixedState: method, which allows the cell to be in NSMixedState mode in addition to NSOnState and NSOffState. In addition, various bezel styles have been added to support the range of button styles available on the Mac:

 

• NSRoundedBezelStyle
• NSRegularSquareBezelStyle
• NSThickSquareBezelStyle
• NSThickerSquareBezelStyle.

(Although the header file refers to NSNeXTBezelStyle, NSPushButtonBezelStyle, NSSmallIconButtonBezelStyle, NSMediumIconButtonBezelStyle, and NSLargeIconButtonBezelStyle, these styles are obsolete and should not be used.)

 

Java

The Rhapsody Developer release contains an alpha version of the Java APIs for the Yellow Box. By using these APIs you can access virtually all classes and protocols of the Application Kit and Foundation frameworks. However, since this is an alpha version, these APIs are not yet complete and will most likely change before the next release. See the Java APIs release note for details.

Interface Style

The constant NSMacintoshInterfaceStyle has been added to represent the Rhapsody user interface. NSNextStepInterfaceStyle has been removed.

When creating resources, use the suffixes "-macintosh" and "-windows" to indicate any resources that are specific to a particular interface style. The base resource must be available (for instance, foo.nib); all the other interface-style specific ones (such as foo-windows.nib) are optional.

Rhapsody Menu Layout

The recommended menu layout for PowerPC and non-Windows Intel platforms has not yet been finalized; however, this section contains some preliminary guidelines. The standard root menus are:

• Info
• File
• Edit
• Format
• Windows
• Services
• Help

Info

If you give the first menu the name of "Info", the Application Kit replaces the name with the Apple logo. The standard items of the Info menu are:

 

About <Name of Application> ...

About <Plug-ins or Bundles; Hierarchical >

If your application supports an extensive plug-in architecture, or regularly uses bundles to extend its functionality, you should allow for a hierarchical menu item where developers can put About boxes (info panels) about their specific plug-in.)

Preferences

Include only if the application has a preferences panel

<Divider Line>

Hide <Name of Application>

Command-H

Hide Others

Will invoke the application object's hideOtherApplications:; disabled for now. Command-Shift-H.

Show All

Will invoke the application object's unhideOtherApplications:; disabled for now.

 

The Application Kit completes the rest of this menu.

 

File

This menu contains commands specific to documents (or files). You can change the name to reflect the type of object or content the application acts on.

 

New

Command-N

Open

Command-O

<Divider Line>

Close

Command-W

Save

Command-S

Save As

Command-Shift-S

<Divider Line>

<Application Specific Commands>

<Divider Line:>

Page Setup

Command-Shift-P

Print...

Command-P

(Divider Line)

Quit

Command-Q

 

Edit

This menu provides access to commands for editing document content.

Undo

Command-Z (Disabled for now)

Redo

Command-Shift-Z (Disabled for now)

Cut

Command-X

Copy

Command-C

Paste

Command-V

Clear

<Divider Line>

Select All

Command-A

<Divider Line>

Find

Find submenu, stays the same as OpenStep for now.

<Divider Line>

Spelling...

Command-:

Check Spelling

Command-;

<Divider Line>

<Application-Specific Commands>

<Divider Line>

Show Clipboard

Can connect to showPasteboard: in NSApp; will be disabled for now.

Format

Stays the same as OpenStep for now.

 

Windows

Stays the same as OpenStep for now.

 

Services

Stays the same as OpenStep for now.

 

Help

Help...

Command-?

<Divider Line>

<Extra Application Specific Help Topics>

Known Problems

NSComboBox

Reference	71826
Problem	NSComboBox should support keyboard interface.
Description	NSComboBox does not support keyboard equivalents to open, dismiss, or navigate its popup list.
Workaround	None.

NSTableView

Reference	51731
Problem	NSTableView does not fully support keyboard interface.
Description	Although you can tab between editable cells in NSTableView, pressing arrow keys does not affect the selection.
Workaround	Override keyDown: in a subclass or in the owning window and change the selection accordingly.

Note: NSTableView does not yet have printing support.

NSCell

Reference	52511
Problem	The setUpFieldEditorAttributes: method is invoked only when editing occurs.
Description	The setUpFieldEditorAttributes: method is not invoked when non-editable text is displayed in cells. This makes it difficult to change colors in custom subclasses of NSCell.
Workaround	Instead of displaying colored text in cells, use text fields or attributed strings.

NSImage

Reference	60413
Problem	JPEG TIFFs don't work on Windows.
Description	Because the imageserver process is not yet available under Windows, JPEG TIFFs cannot be loaded in.
Workaround	None. Compress images using another compression scheme; for example, you can use the tiffutil utility on Mach.

Text System

Reference	58479
Problem	Rotated text views don't handle selection very well.
Description	The selection drawing (at least) in a rotated NSTextView has some problems, namely that the selection is drawn too large and pixels are left around.
Workaround	None. Avoid editable rotated NSTextViews for now.

NSButton

Reference	1673526
Problem	Unexplained mnemonic on button.
Description	Sometimes mnemonics are displayed on alternate titles of buttons in the Macintosh interface style.
Workaround	Explicitly clear the mnemonic information at runt ime.

NSWindow

Reference	71648
Problem	Closing a modal window or panel does not always end the modal session.
Description	Closing a modal window or panel by clicking the close box does not always end the modal session; this situation leaves the application in a state where mouse clicks and key strokes are ignored. On Windows, modal panels often have a close box. This control acts the same as a cancel button and, by default, clicking the close box while running modal stops the modal session with the NSCancelButton return code. However, if the Window's delegate decides to control when the window should close by implementing windowShouldClose:, then it is also up to the delegate to stop the modal session in windowWillClose:. On Mach, modal windows and panels rarely have a close box; if they do, they must end modal mode in windowWillClose:.
Workaround	On Windows, a window delegate implementing windowWillClose: should stop the modal session in that method. On Mach, the delegate of any modal window or panel with a close box should stop the modal session in windowWillClose:.

Drag and Drop

Reference	60829
Problem	On Windows, ignoreModifierKeysWhileDragging is never invoked on drag source.
Workaround	None.

NSFont

Reference	61824
Problem	Microsoft's WingDings font is not supported well in Yellow Box for Windows.
Description	There currently is no Unicode mapping for any of the glyphs in the WingDings font, even in the User Zone, so the font works as any other "unknown" font (that is, characters 0-255 are mapped directly to glyphs 0-255).
Workaround	None.

NSFontPanel

Reference	1682324
Problem	Error in NSFontManager documentation
Description	The documentation for NSFontManager states that the method fontManager:willIncludeFont: is sent to the delegate of NSFontManager. This is not the case. This method is sent by the font panel (NSFontPanel) to its delegate.
Workaround	Have the delegate of NSFontPanel respond to the fontManager:willIncludeFont: message.

Keyboard UI

Reference	51182
Problem	Accesory views are not added to the keyView loop.
Description	When a panel with an accessory view (such as supported by the Save Panel, for example) is displayed, the accessory view is not automatically added to the keyView loop. Thus the objects in the accessory view do not receive key focus when the user tabs through the panel.
Workaround	Add the accessory view to the keyView loop by invoking setNextKeyView: before displaying the panel.

NSPrintPanel

Reference	1676944
Problem	Faxing is disabled.
Description	Faxing does not work in the Developer Release; because of this, the Fax button in the Print panel is disabled.
Workaround	None.

Accessory Views

On Windows, the Page Layout panel does not yet support application-supplied accessory views. Also on Windows, accessory views in the Open, Save, and Print panels work only on NT 4.0, not NT 3.51.

Notes Specific to OPENSTEP 4.2 (NeXT)

New Features

Vertical Split View

NSSplitView now supports vertical splits as well as horizontal splits.

ToolTips

It's now possible to add "tooltips" (short help messages that pop up as the user holds the mouse cursor over an item) to views. You can do this programmatically or by using Interface Builder's Help panel.

Note that tooltips are currently not archived with views. However, if you set a tooltip in IB, they will be correctly saved in the nib file, so this is not a serious issue.

Text Hyphenation and Justification

The text object now supports full justification and hyphenation. The API is fairly basic at this point. For hyphenation, you specify a hyphenation factor in the range 0.0 to 1.0. Whenever (width of the real contents of the line) / (the line fragment width) is below this value, hyphenation will be attempted when laying out the line. By default, the value is 0, meaning hyphenation is off. A factor of 1.0 causes the text object to always attempt hyphenation. Note that hyphenation slows down text layout and increases memory usage, so it should be used sparingly.

You can save the hyphenation factor in an RTF file by specifying a value for @"HyphenationFactor" in the document attributes dictionary.

ComboBoxCell

There is now a public NSComboBoxCell class. This feature allows you to use combo boxes in table views, among other places.

NSApplication

Support for the "hide application" command has been added to OPENSTEP for Windows. The default menu item for this is Minimize All in the Windows menu (with Control-h as the key equivalent). The Application Kit adds this item automatically if it is not in the menu.

NSColor

A bug in decodeNXColor that caused CMYK colors from 3.x archives to be read incorrectly in 4.0 and 4.1 has been fixed. (The colors were way off base; instead of C, M, Y, K, the values 1-C, 1-M, 1-Y, and 1-K were used.)

Notes Specific to OPENSTEP 4.1 (NeXT)

New Features

ComboBox

The NSComboBox class has been added to the Application Kit. It offers functionality that is similar to the Combo Box control used in the Microsoft Windows user interface.

Splash Screen

OPENSTEP for Windows now provides support for a "splash" screen in applications; this is basically a panel that comes up with a static image as the application is launched. To use this feature, simply provide an 8-bit uncompressed bitmap (.bmp) image named Splash.bmp as a resource in your application. You can make it localizable if you wish (thus the image can be either in appname .app/Resources or appname .app/Resources/language .lproj.) At launch time, the image is loaded and displayed before any other initialization occurs in the application, and is removed before the first window is displayed.

NSApplication

The default value of the NSUseRunningCopy command-line option has been changed to YES. This means that anytime you launch a second copy of the application, that copy connects you to the original instance of the application . If you wish to run multiple copies of an application, you should use specify a value of "NO" to the above command-line option. This technique comes in handy if you need to debug a new instance of the application while it's already running.

In addition, all command-line options that are not defaults options (meaning a pair of arguments where the first one starts with a "-") are now treated as file names to be opened, as if they were prefixed with -NSOpen.

As a result of these two changes, you can now associate documents with OpenStep applications on Windows simply by specifying the location of the application. The default command line provided by the Explorer suffices to open documents and also to connect to a running copy of the application, if there is one.

NSWindow

In OPENSTEP for Windows, an asterisk in a window's title bar indicates that the associated document has been edited. OPENSTEP for Mach still uses a broken "X" to indicate this state. In addition, tracking rectanbles are now implemented on Windows.

There are two things related to windows on Windows to watch out for:

• The frameRect and contentRect are currently the same size. The frameRect of an NSWindow under OPENSTEP for WIndows NT does not include the title bar, menu bar, resize border, and so on.
  
  
• The contentView while a window is miniaturized is a NSImageView, not the original contentView. The contentView is restored when the window is deminiaturized. This sequence is necessary because under some versions of Windows NT, the same actual window is used when the window is full size or miniaturized. It is simply moved and resized during miniaturing or restoring operations. Since most content views are not prepared to size themselves that small, the content view is removed from the window while it miniaturizes and is restored when the window is restored.

NSTextView

On Windows, to allow entering a character without an appropriate keyboard, you can now use the Alternate key in conjunction with the digit keys from the keypad. While holding down the Alternate key, type the index of the desired character in the encoding of the current font (in most cases this will be the NEXTSTEP encoding). The appropriate character will be inserted into the text when the Alternate key is released.

Notes Specific to OPENSTEP 4.0 (NeXT)

New Features

OpenStep

Release 4.0 brings numerous API changes to the AppKit relative to Release 3.3. These changes and the tools provided for applications to convert to OpenStep are described in /NextLibrary/Documentation/NextDev/Conversion/ConversionGuide.

New Text System

Releae 4.0 includes a new text system composed of several different classes: NSTextView (front-end UI), NSTextStorage and NSAttributedString (back-end text storage), NSLayoutManager (management of text layout process and info), and NSTextContainer (description of text flow areas). These classes provide an open, powerful interface and allow text editing in multiple languages, using the Unicode standard. Please refer to the documentation for detailed info. An overview can be found in NextLibrary/Documentation/NextDev/TasksAndConcepts/ProgrammingTopics/TextOverview.rtfd (Mach) or in the NextLibrary/Documentation/NextDev/TasksAndConcepts/Topics.hlp (Windows). There is also a separate release note which describes some of the defaults that can be used to customize the new text system and how to remap or add to the standard supported keybindings. In addition to these notes, the source code to several text-specific examples, including the full source to TextEdit, can be found in the /NextDeveloper/Examples/AppKit directory.

FileWrapper

NSFileWrapper provides support for the concept of a document wrapper (like a .rtfd, .nib, or many other NEXTSTEP file types). The new text system uses this class to handle RTFD documents, but it is designed to be generally useful. It handles reading and writing file packages in the file system as well as serializing them for use with the Pasteboard.

TableView

TableView has been completely rewritten and moved into the AppKit. All four classes making up the new TableView are public and fully subclassable.

Keyboard UI

Keyboard access is now provided to most of the controls in the AppKit.

Formatting and Validation

Cells may now be assigned arbitrary object values, which are converted into presentation strings by associated formatter objects. This allows the developer to directly set an NSDate, for instance, as the value of a cell. The cell's associated date formatter will present a localized string representation of the date to the user. The formatter objects, along with control delegates, can also perform validation on user-entered data, thereby restricting entries to valid ranges or quantities, for instance only allowing dates between January 1, 1995 and June 30, 1995.

Rich Text in Cells

NSCell and subclasses can now display and edit rich text. The rich text is specified via instances of NSAttributedString. The new formatting/validation API also includes support for attributed strings.

RulerView

NSRulerView is designed as a general-purpose ruler that can be associated with any scroll view and used by any view that's in the scroll view. It supports both horizontal and vertical rulers, allows arbitrary markers along the rule, and can accept an accessory view.

System Colors

New API has been added to access system-defined colors, such as the color of buttons, controls, text and text selection colors. On Windows, where the user can change the system colors at any point, these colors will change at runtime to match the user's selection.

Help System

The AppKit's Help API has changed significantly. NSHelpPanel has been obsoleted in favor of a new class, NSHelpManager, which provides a more platform-independent approach to presenting help.

Image

NSImage now understands the bmp, ico, and cur image formats. ico and cur files with multiple images will be loaded as images with multiple representations. Typically these representations will have different sizes (unlike multiple-representation tiffs, which have different depths); by default, NSImage will choose the largest image when compositing.

NSApplicationMain

The AppKit now provides a function NSApplicationMain() to take care of the initialization and startup of your application. This function is declared in NSApplication.h. Because of this, ProjectBuilder will now generate a trivial main function for your application:

#import <AppKit/NSApplication.h>int main(int argc, const char *argv[]) {
    NSApplicationMain(argc, argv);
}
 

ObjectLinks

ObjectLinks have been removed from the OpenStep specification, and in general the feature is not supported in OPENSTEP for Mach or Windows. The exception is that the following subset of the API may be used on either platform to walk through the linked data from documents written in NEXTSTEP 3.X:

@interface NSDataLinkManager : NSObject <NSCoding> {
- (id)initWithDelegate:(id)obj fromFile:(NSString *)path;
- (NSEnumerator *)sourceLinkEnumerator;
- (NSEnumerator *)destinationLinkEnumerator;
@end
 @interface NSDataLink : NSObject <NSCopying, NSCoding>- (NSArray *)types;
- (NSSelection *)sourceSelection;
- (NSSelection *)destinationSelection;
- (NSString *)sourceFilename;



               - (NSString *)currentSourceFilename; 
- (NSString *)destinationFilename;
- (NSString *)sourceApplicationName;
- (NSString *)destinationApplicationName;
- (NSDataLinkManager *)manager;
- (NSDate *)lastUpdateTime;
- (NSDataLinkNumber)linkNumber;
- (NSDataLinkDisposition)disposition;
@end
 @interface NSSelection : NSObject <NSCopying, NSCoding>



               + (NSSelection *)emptySelection;
+ (NSSelection *)allSelection;
+ (NSSelection *)currentSelection;
- (NSData *)descriptionData;
- (BOOL)isWellKnownSelection;
 @end

Note that this API is a subset of the previously provided ObjectLinks API, with one exception: The currentSourceFilename method has been added to NSDataLink to allow the application to query the current location of the source file (whereas the sourceFilename method returns the original name).

Help System

The AppKit's Help API has changed significantly. NSHelpPanel has been obsoleted in favor of a new class, NSHelpManager. NSHelpManager provides a more platform-independent approach to presenting help.

Previously, the only way for your application to present help was through the NEXTSTEP Help panel. Context-sensitive help and all other help for your application was displayed in the Help panel. This made sense when NEXTSTEP was the only platform for your application.

OpenStep applications, however, can run on multiple platforms, and each platform provides its own support for online help. It's important to users that applications use the native online help system (on Windows, for instance, users want the Windows help system and don't want to have to learn how to use a different help system), so NSHelpManager does not provide a comprehensive solution for presenting help. Instead, it provides cross-platform support for context-sensitive help, and allows you to present more comprehensive help (conceptual and task-based help) in any way you choose.

Context Help

Context-sensitive help (also referred to as context help) gives the user a small amount of information when they help-click on an interface item. For example, if the user help-clicks on a menu item called "Copy", they should get context help that says something like "Copies the currently selected text to the pasteboard." This text appears in a small window near where the user help-clicked, and the window disappears when the user clicks anywhere else in the application.

To provide context help for your application, follow these steps:

1. For each interface item that needs context help, create an .rtf or .rtfd file containing the text and any images you want to appear when the user help-clicks on that interface item. Try to keep the text as brief as possible and the images as small as possible.
   
   
2. If you don't need to localize your context help files, in Project Builder simply add these files to the Context Help suitcase of your project. If you do need to localize your context help files, first copy the files into the appropriate .lproj directory of your project, then use Project Builder to add them to the Context Help suitcase of your project.
   
   
3. In Interface Builder, connect each interface item to its context help file by doing the following:
   1. Bring up the Interface Builder inspector and choose the Help display. The Help display lists all the context help files associated with your application.
   2. Select an interface item.
   3. In the inspector, choose the appropriate help file.

When you compile your application, /usr/bin/compileHelp packages your help files into a property list named Help.plist. NSHelpManager knows how to extract context help from an Help.plist file.

Comprehensive Help

Most applications provide some form of online help that is more comprehensive and detailed than context-sensitive help, such as conceptual or task help. NSHelpManager allows you to provide this sort of comprehensive help in any way you choose. Some help authors prefer to provide comprehensive help in HTML using a World-Wide Web browser; others use tools such as Digital Librarian or Concurrence; on Windows a full-featured native help system is available. Given the availability of rich tools like Digital Librarian and HTML browsers, OpenStep on Mach no longer supplies a native help system for comprehensive help.

When the user chooses the Help menu item, NSHelpManager simply asks the Workspace Manager to open the help file you have specified for your application. That file should be the starting point of your help, and should allow users to access whatever information they might need.

To specify a help file for your application, do one of the following:

• The simplest approach, not requiring you to specify the help file anywhere in your application, is to place the help file in your app wrapper and name it after your application. If you haven't specified a help file, NSHelpManager looks in the app wrapper for an appropriately named file. On Mach, it must be an rtf file called <appName>.rtf. On Windows, it must be a Windows help file called <appName>.hlp.
  
  
• To specify a help file that applies to all platforms, define the NSHelpFile key in your project's CustomInfo.plist file:

  {
  NSHelpFile = "ApplicationHelp.rtfd";
  }

  If your project does not have a CustomInfo.plist, simply create one (as in the example), and add it to your project's "Supporting Files" file category. When you build your project, the contents of CustomInfo.plist will be merged into your application's Info.plist

  The specified value for the NSHelpFile key can be a full or relative path, and if it is relative, it is assummed to be a bundle resource (resolved using [[NSBundle mainBundle] pathForResource:<NSHelpFile value> ofType:nil]).

Localization

There are several localization features that are not documented elsewhere:

It's possible to change the order of the arguments in a localized string by using the "$" modifier and the argument number:

/* Message in alert panel when something fails */
"Oh %@! %@ failed!" = "%2$@ blah blah, %1$@ oh!";

The default NSShowNonLocalizableStrings can be used to catch strings which are not localizable. The strings will be logged and also displayed in the UI in upper case. Note that there will be some false positives, but this is still useful.

The default NSShowNonLocalizedStrings will indicate strings which were meant to be localized but could not be found in the strings files. This can be used to catch problems with out-of-date localizations.